home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 26 / AACD 26.iso / AACD / System / xvs / developer / autodoc / xvs.doc
Encoding:
Text File  |  2001-09-04  |  13.2 KB  |  471 lines
  1. TABLE OF CONTENTS
  2.  
  3. xvs.library/xvsAllocObject
  4. xvs.library/xvsCheckBootblock
  5. xvs.library/xvsCheckFile
  6. xvs.library/xvsCheckSector
  7. xvs.library/xvsCreateVirusList
  8. xvs.library/xvsFreeObject
  9. xvs.library/xvsFreeVirusList
  10. xvs.library/xvsInstallBootblock
  11. xvs.library/xvsObjectType
  12. xvs.library/xvsRepairFile
  13. xvs.library/xvsRepairSector
  14. xvs.library/xvsSelfTest
  15. xvs.library/xvsSumBootblock
  16. xvs.library/xvsSurveyMemory
  17.  
  18. xvs.library/xvsAllocObject                         xvs.library/xvsAllocObject
  19.  
  20.    NAME
  21.     xvsAllocObject -- Allocate memory for specified object.
  22.  
  23.    SYNOPSIS
  24.     object = xvsAllocObject(objecttype)
  25.       D0          -48           D0
  26.  
  27.     APTR xvsAllocObject(ULONG);
  28.  
  29.    FUNCTION
  30.     Allocates a memory block and required resources for the specified
  31.     object. Never do this in any other way for compatibility with
  32.     library updates.
  33.  
  34.     Objecttype can be one of these:
  35.     XVSOBJ_BOOTINFO    - allocate a xvsBootInfo structure.
  36.     XVSOBJ_FILEINFO    - allocate a xvsFileInfo structure.
  37.     XVSOBJ_MEMORYINFO  - allocate a xvsMemoryInfo structure.
  38.     XVSOBJ_SECTORINFO  - allocate a xvsSectorInfo structure.
  39.  
  40.    INPUTS
  41.     objecttype - One of the XVSOBJ_#? values.
  42.  
  43.    RESULT
  44.     object - Pointer to the object or NULL if there occured an error.
  45.  
  46.    SEE ALSO
  47.     xvsFreeObject()
  48.  
  49. xvs.library/xvsCheckBootblock                   xvs.library/xvsCheckBootblock
  50.  
  51.    NAME
  52.     xvsCheckBootblock -- Check bootblock contents for viruses.
  53.  
  54.    SYNOPSIS
  55.     result = xvsCheckBootblock(bootinfo)
  56.       D0            -66           A0
  57.  
  58.     ULONG xvsCheckBootblock(struct xvsBootInfo *);
  59.  
  60.    FUNCTION
  61.     Checks if a bootblock contains viruses and informs about the
  62.     dostype, checksum and type of the bootblock.
  63.  
  64.     xvsbi_Bootblock must be initialized with a pointer to a 1024 bytes
  65.     bootblock.
  66.  
  67.     The bootblock will be first checked for the dostype. If it's not
  68.     a DOS bootblock, you'll receive XVSBT_NOTDOS as a result.
  69.     Otherwise xvsbi_DosType will receive the type of filesystem the
  70.     disk is using (eg. DOS/0 -> xvsbi_DosType = 0).
  71.     The xvsbi_ChkSumFlag field will be TRUE if the bootblock checksum
  72.     is correct (ie. bootable), otherwise it's FALSE.
  73.  
  74.     Now the bootblock will be checked for standard bootblocks and
  75.     viruses. You'll receive XVSBT_STANDARD13, XVSBT_STANDARD20 or
  76.     XVSBT_VIRUS in that case.
  77.  
  78.     If all the tests were negative, XVSBT_UNKNOWN is returned. Note
  79.     that XVSBT_UNINSTALLED will never be returned by this function,
  80.     it is only used by xvsInstallBootblock(). You can consider an
  81.     unknown bootblock with xvsbi_ChkSumFlag set to FALSE as uninstalled.
  82.  
  83.     In all cases, you'll receive the result in xvsbi_BootType too
  84.     and a describing ascii text in xvsbi_Name.
  85.  
  86.    INPUTS
  87.     bootinfo - Pointer to initialized xvsBootInfo structure.
  88.  
  89.    RESULT
  90.     result   - One of the XVSBT_#? values.
  91.  
  92. xvs.library/xvsCheckFile                             xvs.library/xvsCheckFile
  93.  
  94.    NAME
  95.     xvsCheckFile -- Check file contents for viruses.
  96.  
  97.    SYNOPSIS
  98.     result = xvsCheckFile(fileinfo)
  99.       D0         -96         A0
  100.  
  101.     ULONG xvsCheckFile(struct xvsFileInfo *);
  102.  
  103.    FUNCTION
  104.     Checks any file (executable/data) for virus infection and informs
  105.     about the type of file.
  106.  
  107.     IMPORTANT: The file must be in decrunched state, linked files must
  108.     be unlinked first, otherwise this function cannot find all built-in
  109.     viruses. Use xfdmaster.library for this purpose, you'll find it in
  110.     the Aminet too.
  111.  
  112.     xvsfi_File must be supplied with a pointer to the buffer holding
  113.     the file, xvsfi_FileLen must receive the length of the file.
  114.  
  115.     The file will be first checked if it's executable. If not, it's
  116.     a data file and will be scanned for data viruses (eg. scripts,
  117.     bootblocks). If nothing is found, the result is XVSFT_DATAFILE,
  118.     otherwise you'll receive XVSFT_DATAVIRUS. Such files can only be
  119.     deleted.
  120.  
  121.     Executable files are tested for link- and fileviruses. The result
  122.     for linkviruses is XVSFT_LINKVIRUS, you can repair these files with
  123.     a call to xvsRepairFile(). Fileviruses return XVSFT_FILEVIRUS and
  124.     the file can only be deleted completely.
  125.  
  126.     In all cases, you'll receive the result in xvsfi_FileType too
  127.     and a describing ascii text in xvsfi_Name.
  128.  
  129.     After calling this function, always test xvsfi_ModifiedFlag. If
  130.     this is TRUE, the recognition code modified your file buffer and
  131.     it's no longer safe to write it back to disk, execute it etc.
  132.     Some viruses require a lot of decrypt work for recognition and
  133.     it's not possible to detect them without, that's why I had to
  134.     add this flag.
  135.  
  136.    INPUTS
  137.     fileinfo - Pointer to initialized xvsFileInfo structure.
  138.  
  139.    RESULT
  140.     result   - One of the XVSFT_#? values.
  141.  
  142.    SEE ALSO
  143.     xvsRepairFile()
  144.  
  145. xvs.library/xvsCheckSector                         xvs.library/xvsCheckSector
  146.  
  147.    NAME
  148.     xvsCheckSector -- Check disk sector contents for virus modifications.
  149.  
  150.    SYNOPSIS
  151.     result = xvsCheckSector(sectorinfo)
  152.       D0          -84           A0
  153.  
  154.     ULONG xvsCheckSector(struct xvsSectorInfo *);
  155.  
  156.    FUNCTION
  157.     Checks if a sector has been modified by viruses.
  158.  
  159.     xvssi_Sector must be initialized with a pointer to a 512 bytes
  160.     disk sector, xvssi_Key with the sector number it has on disk.
  161.  
  162.     The sector will be checked for damages or changes done by viruses.
  163.     If anything is found, XVSST_DESTROYED or XVSST_INFECTED will be
  164.     returned, otherwise you'll receive XVSST_UNKNOWN.
  165.  
  166.     In all cases, you'll receive the result in xvssi_SectorType too
  167.     and a describing ascii text in xvssi_Name.
  168.  
  169.    INPUTS
  170.     sectorinfo - Pointer to initialized xvsSectorInfo structure.
  171.  
  172.    RESULT
  173.     result     - One of the XVSST_#? values.
  174.  
  175.    SEE ALSO
  176.     xvsRepairSector()
  177.  
  178. xvs.library/xvsCreateVirusList                 xvs.library/xvsCreateVirusList
  179.  
  180.    NAME
  181.     xvsCreateVirusList -- Allocate and initialize xvsVirusList structure.
  182.  
  183.    SYNOPSIS
  184.     viruslist = xvsCreateVirusList(listtype)
  185.        D0              -36            D0
  186.  
  187.     struct xvsVirusList *xvsCreateVirusList(ULONG);
  188.  
  189.    FUNCTION
  190.     Allocates memory for a xvsVirusList structure and initializes it
  191.     with nodes of the required type.
  192.  
  193.     Listtype can be one of these:
  194.     XVSLIST_BOOTVIRUSES  - create list of bootblock viruses.
  195.     XVSLIST_FILEVIRUSES  - create list of file viruses.
  196.     XVSLIST_LINKVIRUSES  - create list of link viruses.
  197.     XVSLIST_DATAVIRUSES  - create list of data viruses.
  198.  
  199.     The list should be used for information purposes only, eg. for a
  200.     listview gadget of gadtools.library.
  201.     xvsVirusList->LH_TYPE holds the XVSLIST_#? value,
  202.     xvsVirusList->xvsvl_Count holds the amount of nodes.
  203.     The nodes themselves hold a pointer to the virus name in the
  204.     LN_NAME field.
  205.  
  206.    INPUTS
  207.     listtype - One of the XVSLIST_#? values.
  208.  
  209.    RESULT
  210.     viruslist - Pointer to xvsVirusList or NULL if not enough memory.
  211.  
  212.    SEE ALSO
  213.     xvsFreeVirusList()
  214.  
  215. xvs.library/xvsFreeObject                           xvs.library/xvsFreeObject
  216.  
  217.    NAME
  218.     xvsFreeObject -- Release memory of object.
  219.  
  220.    SYNOPSIS
  221.     xvsFreeObject(object)
  222.          -54        A1
  223.  
  224.     void xvsFreeObject(APTR);
  225.  
  226.    FUNCTION
  227.     Deallocates the memory and releases the resources reserved via
  228.     xvsAllocObject().
  229.  
  230.    INPUTS
  231.     object - Pointer to object.
  232.  
  233.    RESULT
  234.     None.
  235.  
  236.    SEE ALSO
  237.     xvsAllocObject()
  238.  
  239. xvs.library/xvsFreeVirusList                     xvs.library/xvsFreeVirusList
  240.  
  241.    NAME
  242.     xvsFreeVirusList -- Release memory of xvsVirusList structure.
  243.  
  244.    SYNOPSIS
  245.     xvsFreeVirusList(viruslist)
  246.           -42            A1
  247.  
  248.     void xvsFreeVirusList(struct xvsVirusList *);
  249.  
  250.    FUNCTION
  251.     Deallocates the memory of a xvsVirusList structure that has been
  252.     returned as result by xvsCreateVirusList().
  253.  
  254.    INPUTS
  255.     viruslist - Pointer to a xvsVirusList structure.
  256.  
  257.    RESULT
  258.     None.
  259.  
  260.    SEE ALSO
  261.     xvsCreateVirusList()
  262.  
  263. xvs.library/xvsInstallBootblock               xvs.library/xvsInstallBootblock
  264.  
  265.    NAME
  266.     xvsInstallBootblock -- Install some standard bootblocks to buffer.
  267.  
  268.    SYNOPSIS
  269.     xvsInstallBootblock(bootblock, boottype, dostype)
  270.             -72            A0         D0        D1
  271.  
  272.     void xvsInstallBootblock(APTR, ULONG, ULONG);
  273.  
  274.    FUNCTION
  275.     Installs desired bootblock data to the buffer. The checksum will
  276.     be corrected automatically except for XVSBT_UNINSTALLED bootblocks.
  277.  
  278.     Boottype can be one of these:
  279.     XVSBT_UNINSTALLED - creates uninstalled (non-bootable) bootblock.
  280.     XVSBT_STANDARD13  - creates standard bootblock (Kickstart 1.3).
  281.     XVSBT_STANDARD20  - creates standard bootblock (Kickstart 2.0).
  282.  
  283.     Dostype specifies the filesystem the disk is using. It's just
  284.     the trailing number behind 'DOS', eg. DOS/0 -> dostype = 0.
  285.  
  286.    INPUTS
  287.     bootblock - Pointer to buffer that is 1024 bytes long.
  288.     boottype  - One of the XVSBT_#? values above.
  289.     dostype   - Any reasonable number from 0 to xx.
  290.  
  291.    RESULT
  292.     None.
  293.  
  294. xvs.library/xvsObjectType                           xvs.library/xvsObjectType
  295.  
  296.    NAME
  297.     xvsObjectType -- Determine type of object.
  298.  
  299.    SYNOPSIS
  300.     objecttype = xvsObjectType(object)
  301.         D0            -60        A1
  302.  
  303.     ULONG xvsObjectType(APTR);
  304.  
  305.    FUNCTION
  306.     Checks if object points to a XVSOBJ_#? object and returns the type
  307.     of this object if possible.
  308.  
  309.    INPUTS
  310.     object - Pointer to a possible XVSOBJ_#? object.
  311.  
  312.    RESULT
  313.     objecttype - One of the XVSOBJ_#? values or NULL if not an object.
  314.  
  315.    SEE ALSO
  316.     xvsAllocObject()
  317.  
  318. xvs.library/xvsRepairFile                           xvs.library/xvsRepairFile
  319.  
  320.    NAME
  321.     xvsRepairFile -- Repair linkvirus-infected file.
  322.  
  323.    SYNOPSIS
  324.     success = xvsRepairFile(fileinfo)
  325.       D0          -102         A0
  326.  
  327.     BOOL xvsRepairFile(struct xvsFileInfo *);
  328.  
  329.    FUNCTION
  330.     Tries to repair files that have been detected as XVSFT_LINKVIRUS
  331.     by xvsCheckFile().
  332.  
  333.     This function will first test the hunk structure of the file
  334.     to be repaired to avoid serious problems during repair action.
  335.     For recognition this was not necessary and not wanted in order
  336.     to detect viruses in corrupted files too.
  337.  
  338.     If success is TRUE, everything worked well, the virus has been
  339.     removed. You can save back the file to disk using xvsfi_Fixed
  340.     as start pointer and xvsfi_FixedLen as new file length.
  341.     Please note that these two fields don't describe a new buffer but
  342.     are only position and length information from within your own
  343.     buffer (from xvsfi_File). Don't release your buffer before saving
  344.     the fixed file.
  345.  
  346.     If success is FALSE, an error occured. You get a describing error
  347.     code from xvsfi_ErrorCode and the corresponding ascii string from
  348.     xvsfi_Name.
  349.     In case of an error it might be of interest if the buffer had
  350.     already been modified before the error occured or not. To find out,
  351.     check xvsfi_ModifiedFlag (TRUE = modified).
  352.  
  353.    INPUTS
  354.     fileinfo - Pointer to initialized xvsFileInfo structure.
  355.  
  356.    RESULT
  357.     success  - TRUE if file is repaired, FALSE if an error occured.
  358.  
  359.    SEE ALSO
  360.     xvsCheckFile()
  361.  
  362. xvs.library/xvsRepairSector                       xvs.library/xvsRepairSector
  363.  
  364.    NAME
  365.     xvsRepairSector -- Repair virus-encrypted sector.
  366.  
  367.    SYNOPSIS
  368.     success = xvsRepairSector(sectorinfo)
  369.       D0           -90            A0
  370.  
  371.     BOOL xvsRepairSector(struct xvsSectorInfo *);
  372.  
  373.    FUNCTION
  374.     Tries to repair sectors that have been detected as XVSST_INFECTED
  375.     by xvsCheckSector().
  376.  
  377.     Call this function after xvsCheckSector() returned XVSST_INFECTED
  378.     and there will never occur an error. You can then write back the
  379.     cleaned sector to disk.
  380.  
  381.    INPUTS
  382.     sectorinfo - Pointer to initialized xvsSectorInfo structure.
  383.  
  384.    RESULT
  385.     success    - TRUE if repaired, FALSE if failed.
  386.  
  387.    SEE ALSO
  388.     xvsCheckSector()
  389.  
  390. xvs.library/xvsSelfTest                               xvs.library/xvsSelfTest
  391.  
  392.    NAME
  393.     xvsSelfTest -- Test xvs.library for modifications.
  394.  
  395.    SYNOPSIS
  396.     success = xvsSelfTest()
  397.       D0         -30
  398.  
  399.     BOOL xvsSelfTest(void);
  400.  
  401.    FUNCTION
  402.     Tests the file structure of xvs.library for modifications. Call this
  403.     function whenever you first open xvs.library to verify its contents.
  404.  
  405.    INPUTS
  406.     None.
  407.  
  408.    RESULT
  409.     success - TRUE if xvs.library is ok, FALSE if anything is changed.
  410.  
  411. xvs.library/xvsSumBootblock                       xvs.library/xvsSumBootblock
  412.  
  413.    NAME
  414.     xvsSumBootblock -- Correct bootblock checksum.
  415.  
  416.    SYNOPSIS
  417.     xvsSumBootblock(bootblock, offset)
  418.           -78          A0        D0
  419.  
  420.     void xvsSumBootblock(APTR, ULONG);
  421.  
  422.    FUNCTION
  423.     Calculates the correct checksum for a bootblock and writes it to
  424.     the longword specified by offset.
  425.  
  426.     Offset must be a multiple of 4, otherwise the bootblock will not
  427.     be bootable.
  428.  
  429.    INPUTS
  430.     bootblock - Pointer to buffer holding 1024 bytes bootblock.
  431.     offset    - Offset from beginning of buffer to write checksum to.
  432.  
  433.    RESULT
  434.     None.
  435.  
  436. xvs.library/xvsSurveyMemory                       xvs.library/xvsSurveyMemory
  437.  
  438.    NAME
  439.     xvsSurveyMemory -- Check memory for viruses and remove them if any.
  440.  
  441.    SYNOPSIS
  442.     count = xvsSurveyMemory(memoryinfo)
  443.      D0           -108          A0
  444.  
  445.     ULONG xvsSurveyMemory(struct xvsMemoryInfo *);
  446.  
  447.    FUNCTION
  448.     Checks memory for any known viruses and removes them immediately.
  449.  
  450.     xvsMemoryInfo is just an information structure that holds the
  451.     results of a memory check, you don't have to initialize it with
  452.     any values first.
  453.  
  454.     xvsmi_Count holds the same value as returned by this function.
  455.     xvsmi_NameArray holds pointers to the names of the detected viruses.
  456.     There are always xvsmi_Count pointers valid, if count is zero, no
  457.     pointers are valid.
  458.  
  459.     The amount of names is limited to 5, but from my experience I can
  460.     say that this should be enough. It's very unrealistic that someone
  461.     has more than 5 active viruses running on his machine without a
  462.     complete system crash. Nevertheless, ALL viruses will be killed,
  463.     but only the first 5 will be listed if there should ever be more.
  464.  
  465.    INPUTS
  466.     memoryinfo - Pointer to xvsMemoryInfo structure.
  467.  
  468.    RESULT
  469.     count      - Amount of detected and removed viruses.
  470.  
  471.